Skip to content

Restore missing SDK client docs in API reference#434

Merged
timmarkhuff merged 4 commits into
mainfrom
fix/sphinx-docs-missing-pyyaml
May 15, 2026
Merged

Restore missing SDK client docs in API reference#434
timmarkhuff merged 4 commits into
mainfrom
fix/sphinx-docs-missing-pyyaml

Conversation

@timmarkhuff
Copy link
Copy Markdown
Contributor

@timmarkhuff timmarkhuff commented May 15, 2026

Summary

The API reference docs page (/api-reference-docs/) was missing all content for Groundlight and ExperimentalApi -- only the API response object models were rendering.

Root cause: PR #413 ("Migrate Edge Configuration to SDK") introduced groundlight/edge/config.py, which does import yaml. PR #419 ("SDK Configures Edge") then wired this into the import chain accessible from groundlight/__init__.py. When sphinx builds the docs, it installs only the sphinx-deps dependency group (via poetry install --no-root --only sphinx-deps). Since pyyaml was not in that group, sphinx's autodoc failed to import groundlight.Groundlight and groundlight.ExperimentalApi with No module named 'yaml'. Sphinx treated this as a non-fatal warning and silently omitted those sections from the built docs. The docs have been broken since the April 7 deploy.

Changes

  • pyproject.toml: Removed duplicate dependencies from sphinx-deps that were already in the main deps group (pillow, pydantic, python-dateutil). The sphinx-deps group now only contains sphinx-specific packages.
  • Makefile: Changed install-sphinx-deps to install both the main and sphinx-deps groups (--only main --only sphinx-deps), so sphinx always has access to whatever the SDK imports. Also added -W to SPHINXOPTS so sphinx treats warnings as errors -- CI will now fail immediately if autodoc can't import a documented class, preventing this class of silent breakage in the future.
  • sphinx_docs/conf.py: Removed html_static_path entry referencing a non-existent _static directory.
  • sphinx_docs/models.rst: Added EdgeEndpointApi as a documented class under a new "Edge Endpoint API" section.
  • src/groundlight/edge/api.py: Improved EdgeEndpointApi class docstring to explain how it's accessed (gl.edge).
  • src/groundlight/client.py and src/groundlight/experimental_api.py: Fixed pre-existing RST docstring formatting issues (indentation errors, missing :: on code block headers, trailing underscores interpreted as hyperlink references) that -W surfaced.

@timmarkhuff timmarkhuff changed the title fixing broken documentation Restore missing SDK client docs in API reference May 15, 2026
@timmarkhuff timmarkhuff merged commit e6178a8 into main May 15, 2026
15 of 16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants